feat: disambiguate media files by prefix via query parameter#15844
Open
tschwartz wants to merge 2 commits intopayloadcms:mainfrom
Open
feat: disambiguate media files by prefix via query parameter#15844tschwartz wants to merge 2 commits intopayloadcms:mainfrom
tschwartz wants to merge 2 commits intopayloadcms:mainfrom
Conversation
Add optional `?prefix=` query string support to the existing `/api/:collection/file/:filename` endpoint to disambiguate files that share the same filename but have different storage prefixes. When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same `filename`. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval. - `checkFileAccess` accepts optional `prefix` and adds it to the `where` clause alongside existing access filters - `getFile` handler reads `prefix` from `req.searchParams` and threads it to `checkFileAccess` and handler `params` - `getFilePrefix` accepts `explicitPrefix` to skip the DB query when the prefix is already known from the URL - S3 `staticHandler` forwards `prefix` from params to `getFilePrefix` - `afterRead` hook appends `?prefix=` to Payload-proxied URLs - Added unit tests for `checkFileAccess` and `getFilePrefix`, and integration tests for the endpoint'
tschwartz
commented
Mar 4, 2026
| try { | ||
| const prefix = await getFilePrefix({ clientUploadContext, collection, filename, req }) | ||
| const prefix = await getFilePrefix({ | ||
| clientUploadContext, |
Author
There was a problem hiding this comment.
It would have been nice to have added the prefix to the clientUploadContext but the unknown type would require a bunch of checks here in addition to all the checks already in the getFilePrefix function.
| ], | ||
| }, | ||
| }, | ||
| { |
Author
There was a problem hiding this comment.
Its this correct? Really unsure about this particular bit.
56ba0eb to
170b95e
Compare
When a media URL already contains query parameters, appending the imageCacheTag with '?' produces a malformed URL with double '?'. Check for existing query parameters and use '&' as the separator when needed, matching the pattern already used in the Thumbnail component.
a0c9916 to
de5df42
Compare
GermanJablo
approved these changes
Mar 10, 2026
Contributor
GermanJablo
left a comment
There was a problem hiding this comment.
One minor note (non-blocking)
Only the S3 storage adapter is updated. Other storage adapters (Azure, GCS, Vercel Blob, etc.) aren't changed. This is fine since the core changes (checkFileAccess, getFile) work independently. Other adapters can be updated separately.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add optional
?prefix=query string support to the existing/api/:collection/file/:filenameendpoint to disambiguate files that share the same filename but have different storage prefixes.When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same
filename. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval.checkFileAccessaccepts optionalprefixand adds it to thewhereclause alongside existing access filtersgetFilehandler readsprefixfromreq.searchParamsand threads it tocheckFileAccessand handlerparamsgetFilePrefixacceptsexplicitPrefixto skip the DB query when the prefix is already known from the URLstaticHandlerforwardsprefixfrom params togetFilePrefixafterReadhook appends?prefix=to Payload-proxied URLscheckFileAccessandgetFilePrefix, and integration tests for the endpoint'